Skip to content

docs: P0 audit fixes — resolve contradictions, hand over the keys#3092

Merged
os-zhuang merged 1 commit into
mainfrom
docs/p0-audit-fixes
Jul 17, 2026
Merged

docs: P0 audit fixes — resolve contradictions, hand over the keys#3092
os-zhuang merged 1 commit into
mainfrom
docs/p0-audit-fixes

Conversation

@os-zhuang

Copy link
Copy Markdown
Contributor

背景

对全站文档做了客户视角审计(8 个并行审计员逐页精读 110 页手写指南 + 抽样生成参考,统一评估框架:定位/可运行示例/覆盖面/闭环/AI 视角/排错)。总结论:概念层能理解,动手层会卡住。本 PR 是审计修复的第一批(P0)——全部为"文档自相矛盾/教死 API/关键钥匙缺失"类,每处都有源码依据。

矛盾修正(文档两处说法打架,或在教已死的 API)

  • OWD 词汇:permissions-matrix 的表格/示例/callout 全部改为 canonical 四值(public_read 等,ADR-0090 D4 已移除 legacy 别名 —— spec object.zod.ts:940 白纸黑字);原页 callout 还在说"legacy 两者皆可"
  • referenceFilters 死 API:relationships.mdx 明确它 schema-accepted-but-inert,fields.mdx 却当正例教 —— 改为结构化 lookupFilters + dependsOn;field-types/validation-rules 属性表标注 Legacy
  • percent 语义:三页三种说法(0-100 / 0-1 / decimal)—— 统一为小数存储(0.85 = 85%,与 UI 渲染一致)
  • hook input 形状:插件教程 handler 用扁平 input.first_name、测试传 {doc:{...}}、kernel/events.mdx 契约是 {doc} —— 三处统一到 {doc}
  • libsql:self-hosting 说可用 libsql://,与 env-vars/drivers 两页"不支持"矛盾(该驱动在 Cloud 仓库)—— 修正并在 backup 页限定
  • api/index MCP 行:"无需 per-action 开关"是 Security: MCP action surface must gate on ai.exposed — action bodies run trusted (unbounded RLS/FLS), so invoke-time is the only agent boundary (#2849) #2849 之前的旧表述,与 ai.exposed 治理直接冲突 —— 修正
  • permission-metadata:"roles is the only canonical role field"违反自家 D3 词汇冻结 —— 改 positions
  • common-patterns:自称 copy-pasteable 但示例过不了自家 validate gate —— 全部对象补 sharingModel(含 controlled_by_parent 教学点)+ 页首 namespace 前缀警告

钥匙补齐(此前的文档死胡同)

  • 主路径登录墙:build-with-claude-code 第 5 步补 seeded dev admin 凭据(admin@objectos.ai/admin123);bare osnpx os;MCP 接入补 localhost 示例
  • api/index 新增 Authentication 节:session sign-in + API key(POST /api/v1/keys,x-api-key: osk_…)—— 此前整个 api 板块不告诉你 token 从哪来
  • self-hosting 新增 First boot 节:首个注册用户 = bootstrap admin(生产无 dev 凭据的说明)
  • vercel:InMemoryDriver 冷启动丢数据警告
  • 前置条件:脚手架路径只需 Node 18+(pnpm/TS 是 monorepo 场景,原表格误导)
  • kernel/services-checklist 加过时横幅;quick-reference 摘掉两个 404 链接;examples/docker 坏链改指 docker/(连 docker/README 一起)

验证

  • pnpm --filter @objectstack/docs build ✅(含 spec gen,MDX 全量编译通过)
  • 每处修改的事实依据均来自 spec/runtime 源码或既有正典文档页(commit message 有对照)

🤖 Generated with Claude Code

Fixes the highest-leverage findings from the full docs audit (110 guide
pages reviewed against a customer-comprehension rubric).

Contradiction fixes (docs said two different things, or taught dead APIs):
- OWD: permissions-matrix table/example/callout now use the canonical four
  sharingModel values (ADR-0090 D4) instead of removed legacy aliases
- referenceFilters taught as a positive example while relationships.mdx
  documents it as schema-accepted-but-inert — fields.mdx now teaches
  structured lookupFilters + dependsOn; property tables mark it Legacy
- percent semantics unified to fraction storage (0.85 = 85%) across
  fields/decision-tree (validation-rules already had it right)
- hook input shape unified to the `{ doc }` contract (plugins tutorial
  handler + test now match kernel/events.mdx)
- libsql:// removed from self-hosting env table (driver ships in Cloud,
  not the open framework); backup page Turso section qualified
- api/index MCP row: actions require the author's ai.exposed opt-in
- permission-metadata: `positions` (not `roles`) is the canonical field
- common-patterns: all pattern objects now declare sharingModel and the
  page warns about namespace prefixes — examples pass the gate they teach

Key handovers (previously undocumented dead-ends):
- build-with-claude-code: seeded dev admin credentials at the verify step,
  npx os invocations, localhost MCP connect example
- api/index: new Authentication section (session sign-in + API keys)
- self-hosting: "First boot: create the admin" section (first signup =
  bootstrap admin); fixed dead examples/docker links (also docker/README)
- vercel: warn that InMemoryDriver loses data on every cold start
- getting-started prerequisites: Node 18+ only for the scaffold path
- kernel/services-checklist: stale-status warning banner
- quick-reference: unlink two non-existent reference pages

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@vercel

vercel Bot commented Jul 17, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
spec Ready Ready Preview, Comment Jul 17, 2026 6:55am

Request Review

@github-actions github-actions Bot added documentation Improvements or additions to documentation size/m labels Jul 17, 2026
@os-zhuang
os-zhuang merged commit 84b92b0 into main Jul 17, 2026
15 of 17 checks passed
@os-zhuang
os-zhuang deleted the docs/p0-audit-fixes branch July 17, 2026 06:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation size/m

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant